.\" $Id: PAPI_state.3,v 1.10 2004/09/27 19:41:09 london Exp $
.TH PAPI_state 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_state \- return the counting state of an EventSet

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int\ PAPI_state (int " EventSet ", int *" status ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_state(C_INT\  EventSet,\  C_INT\  status,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B PAPI_state() 
returns the counting state of the specified event set.

.SH ARGUEMENTS
.I "EventSet"
--  an integer handle for a PAPI event set as created by
.BR "PAPI_create_eventset" (3)
.LP
.I status
-- an integer containing a boolean combination of 
one or more of the following nonzero constants as 
defined in the PAPI header file papi.h:

.TS
allbox tab($);
lB l.
PAPI_STOPPED$EventSet is stopped
PAPI_RUNNING$EventSet is running
PAPI_PAUSED$EventSet temporarily disabled by the library
PAPI_NOT_INIT$EventSet defined, but not initialized
PAPI_OVERFLOWING$EventSet has overflowing enabled
PAPI_PROFILING$EventSet has profiling enabled
PAPI_MULTIPLEXING$EventSet has multiplexing enabled
PAPI_ACCUMULATING$reserved for future use
PAPI_HWPROFILING$reserved for future use
.TE

.SH RETURN VALUES
On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ENOEVST"
The EventSet specified does not exist.

.SH EXAMPLES
.nf         
.if t .ft CW
int EventSet = PAPI_NULL;
int status = 0;  

if (PAPI_create_eventset(&EventSet) != PAPI_OK)
  handle_error(1);

/* Add Total Instructions Executed to our EventSet */

if (PAPI_add_event(EventSet, PAPI_TOT_INS) != PAPI_OK)
  handle_error(1);

/* Start counting */

if (PAPI_state(EventSet, &status) != PAPI_OK)
  handle_error(1);

printf("State is now %d\en",status);

if (PAPI_start(EventSet) != PAPI_OK)
  handle_error(1);

if (PAPI_state(EventSet, &status) != PAPI_OK)
  handle_error(1);

printf("State is now %d\en",status);
.if t .ft P
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI_start "(3), " 
.BR PAPI_stop "(3) "
